<html><head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta content="text/javascript" http-equiv="content-script-type">
<title>tango.util.Convert</title>

<link rel="stylesheet" type="text/css" href="css/style.css">
<!--[if lt IE 7]><link rel="stylesheet" type="text/css" href="css/ie56hack.css"><![endif]-->
<script language="JavaScript" src="js/util.js" type="text/javascript"></script>
<script language="JavaScript" src="js/tree.js" type="text/javascript"></script>
<script language="JavaScript" src="js/explorer.js" type="text/javascript"></script>
<script>
function anchorFromTitle(title, path, ext) {
  var url = path + title + "." + ext;
  document.write("<a href='" + url + "'>" + title + "</a>");
  }
</script>
</head><body>
<div id="tabarea"></div><div id="explorerclient"></div>
<div id="content"><script>explorer.initialize("tango.util.Convert");</script>
        <table class="content">
                <tr><td id="docbody"><h1><a href="http://www.dsource.org/projects/tango/browser/trunk/tango/util/Convert.d?rev=3791">tango.util.Convert</a></h1>
                
<font color="black">This module provides a templated function that performs value-preserving
 conversions between arbitrary types.  This function's behaviour can be
 extended for user-defined types as needed.</font><br><br>
<b>License:</b><br>
BSD style: see <a href="http://www.dsource.org/projects/tango/wiki/LibraryLicense">license.txt</a><br><br>
<b>Authors:</b><br>
Daniel Keep<br><br>
<b>Credits:</b><br>Inspired in part by Andrei Alexandrescu's work on std.conv.<br><br>
<dl>
<script>explorer.outline.writeEnabled = true;</script>
<dt><span class="decl"><li>D <span class="currsymbol"><a href="http://www.dsource.org/projects/tango/browser/trunk/tango/util/Convert.d?rev=3791#L133">to</a></span>
<script>explorer.outline.addDecl('to');</script>(D,S)(S <span class="funcparam">value</span>);</li></span></dt>
<script>explorer.outline.writeEnabled = false;</script>
<script>explorer.outline.writeEnabled = true;</script>
<dt><span class="decl"><li>D <span class="currsymbol"><a href="http://www.dsource.org/projects/tango/browser/trunk/tango/util/Convert.d?rev=3791#L134">to</a></span>
<script>explorer.outline.addDecl('to');</script>(D,S)(S <span class="funcparam">value</span>, D <span class="funcparam">default_</span>);</li></span></dt>
<script>explorer.outline.writeEnabled = false;</script>
<dd>
<font color="black">Attempts to perform a value-preserving conversion of the given value
 from type S to type D.  If the conversion cannot be performed in any
 context, a compile-time error will be issued describing the types
 involved.  If the conversion fails at run-time because the destination
 type could not represent the value being converted, a
 ConversionException will be thrown.</font><br><br>
<font color="black">For example, to convert the string "123" into an equivalent integer
 value, you would use:<br><br> <pre class="d_code">

 <span class="k">auto</span> <span class="i">v</span> = <span class="i">to</span>!(<span class="k">int</span>)(<span class="sl">"123"</span>);
 
</pre><br><br> You may also specify a default value which should be returned in the
 event that the conversion cannot take place:<br><br> <pre class="d_code">

 <span class="k">auto</span> <span class="i">v</span> = <span class="i">to</span>!(<span class="k">int</span>)(<span class="sl">"abc"</span>, <span class="n">456</span>);
 
</pre><br><br> The function will attempt to preserve the input value as exactly as
 possible, given the limitations of the destination format.  For
 instance, converting a floating-point value to an integer will cause it
 to round the value to the nearest integer value.<br><br> Below is a complete list of conversions between built-in types and
 strings.  Capitalised names indicate classes of types.  Conversions
 between types in the same class are also possible.<br><br> <pre class="d_code">

 <span class="k">bool</span>         &lt;-- <span class="i">Integer</span> (<span class="n">0</span>/!<span class="n">0</span>), <span class="i">Char</span> (<span class="cl">'t'</span>/<span class="cl">'f'</span>), <span class="i">String</span> (<span class="sl">"true"</span>/<span class="sl">"false"</span>)
 <span class="i">Integer</span>      &lt;-- <span class="k">bool</span>, <span class="i">Real</span>, <span class="i">Char</span> (<span class="cl">'0'</span>-<span class="cl">'9'</span>), <span class="i">String</span>
 <span class="i">Real</span>         &lt;-- <span class="i">Integer</span>, <span class="i">String</span>
 <span class="i">Imaginary</span>    &lt;-- <span class="i">Complex</span>
 <span class="i">Complex</span>      &lt;-- <span class="i">Integer</span>, <span class="i">Real</span>, <span class="i">Imaginary</span>
 <span class="i">Char</span>         &lt;-- <span class="k">bool</span>, <span class="i">Integer</span> (<span class="n">0</span>-<span class="n">9</span>)
 <span class="i">String</span>       &lt;-- <span class="k">bool</span>, <span class="i">Integer</span>, <span class="i">Real</span>
 
</pre><br><br> Conversions between arrays and associative arrays are also supported,
 and are done element-by-element.<br><br> You can add support for value conversions to your types by defining
 appropriate static and instance member functions.  Given a type
 the_type, any of the following members of a type T may be used:<br><br> <pre class="d_code">

 <span class="i">the_type</span> <span class="i">to_the_type</span>();
 <span class="k">static</span> <span class="i">T</span> <span class="i">from_the_type</span>(<span class="i">the_type</span>);
 
</pre><br><br> You may also use "camel case" names:<br><br> <pre class="d_code">

 <span class="i">the_type</span> <span class="i">toTheType</span>();
 <span class="k">static</span> <span class="i">T</span> <span class="i">fromTheType</span>(<span class="i">the_type</span>);
 
</pre><br><br> Arrays and associative arrays can also be explicitly supported:<br><br> <pre class="d_code">

 <span class="i">the_type</span>[] <span class="i">to_the_type_array</span>();
 <span class="i">the_type</span>[] <span class="i">toTheTypeArray</span>();

 <span class="k">static</span> <span class="i">T</span> <span class="i">from_the_type_array</span>(<span class="i">the_type</span>[]);
 <span class="k">static</span> <span class="i">T</span> <span class="i">fromTheTypeArray</span>(<span class="i">the_type</span>[]);

 <span class="i">the_type</span>[<span class="k">int</span>] <span class="i">to_int_to_the_type_map</span>();
 <span class="i">the_type</span>[<span class="k">int</span>] <span class="i">toIntToTheTypeMap</span>();

 <span class="k">static</span> <span class="i">T</span> <span class="i">from_int_to_the_type_map</span>(<span class="i">the_type</span>[<span class="k">int</span>]);
 <span class="k">static</span> <span class="i">T</span> <span class="i">fromIntToTheTypeMap</span>(<span class="i">the_type</span>[<span class="k">int</span>]);
 
</pre><br><br> If you have more complex requirements, you can also use the generic to
 and from templated members:<br><br> <pre class="d_code">

 <span class="i">the_type</span> <span class="i">to</span>(<span class="i">the_type</span>)();
 <span class="k">static</span> <span class="i">T</span> <span class="i">from</span>(<span class="i">the_type</span>)(<span class="i">the_type</span>);
 
</pre><br><br> These templates will have the_type explicitly passed to them in the
 template instantiation.<br><br> Finally, strings are given special support.  The following members will
 be checked for:<br><br> <pre class="d_code">

 <span class="k">char</span>[]  <span class="i">toString</span>();
 <span class="k">wchar</span>[] <span class="i">toString16</span>();
 <span class="k">dchar</span>[] <span class="i">toString32</span>();
 <span class="k">char</span>[]  <span class="i">toString</span>();
 
</pre><br><br> The "toString_" method corresponding to the destination string type will be
 tried first.  If this method does not exist, then the function will
 look for another "toString_" method from which it will convert the result.
 Failing this, it will try "toString" and convert the result to the
 appropriate encoding.<br><br> The rules for converting to a user-defined type are much the same,
 except it makes use of the "fromUtf8", "fromUtf16", "fromUtf32" and
 "fromString" static methods.
     </font><br><br></dd>
<script>explorer.outline.writeEnabled = true;</script>
<dt><span class="decl"><li>class <span class="currsymbol"><a href="http://www.dsource.org/projects/tango/browser/trunk/tango/util/Convert.d?rev=3791#L179">ConversionException</a></span>
<script>explorer.outline.addDecl('ConversionException');</script> : Exception;</li></span></dt>
<script>explorer.outline.writeEnabled = false;</script>
<dd>
<font color="black">This exception is thrown when the to template is unable to perform a
 conversion at run-time.  This typically occurs when the source value cannot
 be represented in the destination type.  This exception is also thrown when
 the conversion would cause an over- or underflow.
 </font><br><br>
</dd></dl></td></tr>
                <tr><td id="docfooter">
                        Copyright &copy; 2007 Daniel Keep. :: page rendered by CandyDoc. Generated by <a href="http://code.google.com/p/dil">dil</a> on Sat Aug  2 16:08:32 2008.
                </td></tr>
        </table>
</div>
<script></script>
</body></html>